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1. Abstract 
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The creation of a utility for converting and transforming ambisonic files is described. 

The challenges of making such a utility as independent as possible of the user’s platform 
and of adding a GUI to what was initially a command line tool are detailed. 

Though the original version was released over a year ago, a greatly revised version of 
Ambisuite (ver. 0.6.0 ) is due to be released to coincide with LAC2009. 
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2. Ambisonics 

To represent a soundfield we need a mathematical model. 

Fortunately ... an appropriate mathematical model was de¬ 
veloped in 1784. 
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All generalisations are false, brief ones the more so ... 














population 1784-2009 
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+6 • x 
+c • x 2 
+d ■ x 3 

+ ... 
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y = 


a zero degree 

+6 • x first degree 
+c • x 2 second degree 
+d ■ x 3 third degree 
+... etc. 
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No caves: 


±no cliffs: 
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For three dimensions: 


y= b o 

+M...) + 6a(. - ■) + 6 3 (- - -) 

+&4(...) + 65 (...) + 6 e(- • •) 

+67 (•..) + b $(...) 

+ 6 g(. ..) + 6 io(...) + &n(.. 

+bu(- ■ •) + £>13(• • •) 

+&14(. . .) + £>15(- • •) 


+ ... 


zero degree 
first degree 


second degree 


third degree 
etc. 
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Number of channels 


degree (/) 

zero 

first 

second 

third 


number 

1 

3 
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7 


l 21 + 1 
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degree (l) 
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first 
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third 
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Channel count: 


three dimensions (‘periphony’): 

(i + i ) 2 

two dimensions (‘pantophony’): 

2 / + 1 


That is 

three or more channels for pantophony. 
Four or more channels for periphony. 


(As we shall see one can also have mixed order signal sets 
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The order of an ambisonic signal set, is the highest degree it 
contains. 
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(Terminology is not consistent throughout ambisonic literature, here we present this pa¬ 
per’s, and Ambisuite’s, usage.) 













Here we are discussing: 

• Transforming a representation of the soundfield. 

• which, involves some discussion of recording and/or syn¬ 
thesis of representations of a soundfield. 

We are not discussing decoding (‘playback’). 

One of the beauties of ambisonics is that these are distinct. 

• An ambisonic decoder can accommodate the psychoa¬ 
coustics of the intended listening species. 

• A decoder can be updated if our understanding of psy¬ 
choacoustics advances. 

• A decoder can countenance the size of the audience, the 
number of loudspeakers available, etc., etc., etc. 
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Abstract 


3. Ambisuite 


A computer program to manipulate such signal sets. 

As it is a computer program, implicitly, to manipulate such sig¬ 
nal sets in computer files. 


& O O Ambisuite—GUI 


^ File manipulation 


( File conversion 


Information utilities 


( 

About 



f 

Quit 
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Abstract 


There are an infinite number of possible of channels in such 
files. 


Ambisonics 


Ambisuite 


The channel count rarely helps in determining the nature of 
the signal set: 

Second order periphony has nine channels. 

Fourth order pantophony has nine channels. 

The file must describe itself. 


Information utilities 
File conversion 
File manipulation 
Challenges 
Paper 

A DTD for ambisonic... 

Home Page 
Title Page 

« | ►► ( 

< | ► | 

Page 21 of 87 

Go Back 

Print 

Close 

Quit 













Abstract 


Perl —because I knew it! 

SoX —does all the audio file manipulations. 

Tcl/Tk —to add a gui. 

For terminal use (especially batch processing ...) one only 
needs the first two. 
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For the information utilities in a terminal one only needs the 
first. 



Home Page 


Title Page 


All three are cross-platform. 

All three have a wide user base. One can be confident -for 
example- that SoX offers bug free handling of audio files. 













4. Information utilities 


^ O Ambisuite—GUI 


( File manipulation 

C File conversion"^ 
( Information utilities 


^ About ^ 

( Quit ^ 
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ft ^ OAmbisuite—Information utilities 
( File information ^ 

^ Channels, orders ... ) 

Plane wave values 

Calculator j 

( dose ^ 
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WOO File Information 


/Users/n/Desktop/files.amb/A)H_Brahms_Syml_Mvt4.caf 

( Summary ) 


From metadata chunk: 

Using 'ambisonic-0.03.dtd' DTD. 

Ambisonic B-format. 

(H,V,P) = (1,1,1) (that is T). 
created_with : Ambisuite version 0.6.pre. 
created_on : 20090403 

* 


From file header (via SoXI): 

Channels : 4 
Sample Rate : 48000 
Precision : 16-bit 

Duration : 00:20:55.69 = 60273280 samples ~ 94177 CDDA sectors 
Sample Encoding: 16-bit Signed Integer PCM 
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Channel count implicit in metadata and 
explicit in conventional header: agree. 
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( With source XML ) 


From metadata chunk: 

Using 'ambisonic-0.03.dtd' DTD. 

* 

Ambisonic B-format. 

(H,V,P) = (1,1,1) (that is T). 
created_with : Ambisuite version 0.6.pre. 
created_on : 20090403 


From file header (via SoXI): 

Channels : 4 
Sample Rate : 48000 
Precision : 16-bit 

Duration : 00:20:55.69 = 60273280 samples ~ 94177 CDDA sectors 
Sample Encoding: 16-bit Signed Integer PCM 


Channel count implicit in metadata and 
explicit in conventional header: agree. 

-XML- 

<?xml version="1.0" standalone=*710" ?> 

clDOCTYPE ambisonic PUBLIC "http://ambisonics.ch/dtds/ambisonic-0.03.dtd”> 
<ambisonic> 

<form> 

<b_format> 

dimensions number="3"> 

<dimension H="l" V="l” P="l" /> 

</dimensions> 

</b_format> 

</form> 

<function> 

<tag tag_id="created_with">Ambisuite version 0.6.pre.</tag> 

<tag tag_id="created_on">20090403< /tag> 

</function> 

</ambisonic> 
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Abstract 


The proposed file format: 

1. Complies with the CAF standard. 

2. Must have a uuid chunk. 

• With the uuid 

“5dc3f270c2d24293858e64da38090bea” 
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3. The remainder of the uuid chunk must be xml that com¬ 
plies with 

ambisonics.ch/dtds/ambisonic-0.03.dtd 

or later. 
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Extension to Wavex: 

1 . Complies with the Wavex standard. 

2. Must have a guid which is 
“5dc3f270c2d24293858e64da38090bea” 

3. Must have a ‘AMBI’ chunk that complies with 

ambisonics.ch/dtds/ambisonic-0.03.dtd 

or later. 


But is this worthwhile? 
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Why CAF? 


• File size limit on conventional .wav 

• ... 
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and decoding? 


Connections Manager 

Receive Ports 


\ AmbDec - Co 


► system 

Load Save 

New [ Cancel | Apply 

demo ambt 

▼ ambdec 





Description 

Test 





in_0w 

Matrix scaling 

Input scaling 

Speaker distance 

Near-fiel 

in_lx 

► Normalised 

► Nomnalised 

Delay comp 

None 

in_ly 

Furse-Malham 

Furse-Malham 

► Gain comp. 

On in 

in_lz 





in_2r 


v AmbDec - 0.2.0 

[ambdec] 
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Ambisuite—Information utilities 

HOD File Information 

File information 

/Users/n/Desktop/files.amb/AJH_Brahms_Syrcil_Mvt4.amb 

Channels, orders ... 


Plane wave values 

^ ( Summary ) 

Calculator 

SUMMARY: 


48 KHz / 16 bits / PCM / AMBISONIC 
estimated duration 12S5.699 seconds: 

Close 

^ Return ^ 


^ Close ) 
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File Information 


/Users/n/Desktop/files.amb/A)H_Brahms_Sym l_Mvt4.amb 


( More ir 


40056 

Implicit file size is 40064 bytes. 


extensible (see guid below) 

4 

Implicitly a first order file 
channels (I am guessing) are WXYZ 
48000 blocks/second 
56320 Bytes/second 

8 (size of a block in) Bytes 
bps : 16 bits per sample 

extension : 22 bytes of header extension follows: 

valid bits : 16 per sample 

speakers : no information (CORRECT for ambisonics B-format) 

guid : SUBTYPE_AMBISONIC_B_FORMAT_PCM 

Other strings found early in the file, include: 

PEAK cue sfif data LIST adtlnote sfifDATE 056FA146 


48 KHz / 16 bits / PCM / AMBISONIC 
estimated duration 1255.699 seconds: 
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WOO * File Information 


/Dsers/n/Desktop/files.amb/positions26.wav 


From file header (via SoXI): 

Channels : 4 
Sample Rate : 44100 
Precision : 24-bit 

Duration : 00:02:10.00 = 5733000 samples = 9750 CDDA sectors 
Sample Encoding: 24-bit Signed Integer PCM 


^ Return ^ 
^ Close ^ 
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Ambisuite—Information utilities 

File information 

* 

Channels, ord ers ... 

Plane wave values 

Calculator 


Cose 


O O Information on ambisonic channels 


Enter the channel or signal set name: 


R| 


(E.g:'R\ '6', '2,0', W,'3,0,2'.) 
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^ O Information on ambisonic channels 



Ambisonic Channel Number (ACN): 6 
(l,m) (degree,order): (2,0) 

FuMa letter code: R 

For further information about this channel 
(including spherical harmonic formulae), consult: 
http://ambisonics.ch/standards/channels/ACN6. 


Return ) 


Abstract 


Ambisonics 


Ambisuite 


Information utilities 


File conversion 


File manipulation 


Challenges 


Paper 


A DTD for ambisonic... 


Home Page 


Title Page 


« ►► 


i ► 


Page 36 of 87 


Go Back 


Print 


Close 


Quit 


Close 








































Abstract 


Ambisonics 


Ambisuite 


Information utilities 


File conversion 


File manipulation 


Challenges 


O Information on ambisonic channels 

O Information on ambisonic channels 

ROO Information on ambisonic channels 

Bi , 

CM 

CD 

b 3 

Ambisonic Channel Number (ACN): 1 

Ambisonic Channel Number (ACN): 2 

Ambisonic Channel Number (ACN): 3 

(l,m) (degree.order): (1,-1) 

(l,m) (degree.order): (1,0) 

(l,m) (degree.order): (1,1) 

FuMa letter code: Y 

FuMa letter code: Z 

FuMa letter code: X 

For further information about this channel 
(including spherical harmonic formulae), consult: 
http://ambisonics.ch/standards/channels/ACNl. 

For further information about this channel 
(including spherical harmonic formulae), consult: 
http://ambisonics.ch/standards/channels/ACN2. 

For further information about this channel 
(including spherical harmonic formulae), con 
http://ambisonics.ch/standards/channels/A 

( Return j 

Return_J 

( Return ) 

Close 

Close 

( Close ) 
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Ambisuite—Information utilities 

File information 
Channels, orders ... 

Plane wave values 

Calculator 


dose 
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ft O O Ambisuite—Information utilities 

Information on ambisonic signal sets 

( File information ) 


Channels, orders ... ) 

(H,V,P) notation: 2,2,2 

Malham notation: ff 

Plane wave values ) 

Channel count: 9 

Calculator 

Channels present: 0,1,2,3,4,5,6,7,8 

( Close ") 

Return 
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Abstract 


^ OAmbisuite—Information utilities 
^ File information ) 

Channels, orders ... ^ 

^ Plane wave values ^ 

Calculator 

( Close ) 

D O O Information on ambisonic channels 
Enter the channel or signal set name: 
fh 

(E.g: 'R\ '6', '2,0', 'ffh', '3,0,2'.) 


Calculate 



Information on ambisonic signal sets 


(H,V,P) notation: 2,2,2 
Malham notation: ff 
Channel count: 9 

Channels present: 0,1,2,3,4,5,6,7,8 

Return 

H O Information on ambisonic signal sets 


(H,V,P) notation: 2,0,1 
Malham notation: fh 
Channel count: 6 

Channels present: 0 , 1 , 2 , 3,4 , 8 

^ Return ) 
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n OAmbisuite—Information utilities 


( File information"^ 

( Channels, orders ... ^ 

Plane wave values ) 

Calculator 


^ close } 


O O O Values for plane waves 

Enter the position: 

Azimuth (0 <= theta < 360) 

* 

135 

Elevation (-90 <= phi <= 90) 
-45 

0 Zero Order 
O First Order 
O Second Order 
0 Third Order 
O Fourth Order 
O Fifth Order 
O Sixth Order 
Calculate 
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^ O Plane wave values 

Values for (azimuth, elevation) = (A,E) 
= (theta.phi) = (135,-45) : 


voltage multiplier 



N3D 

3 

channel 

0 

1 

channel 

1 

0.866 

channel 

2 

-1.2247 

channel 

3 

-0.866 

channel 

4 

-0.9682 

channel 

5 

-1.3693 

channel 

6 

0.559 

channel 

7 

1.3693 

channel 

8 

0 

channel 

9 

0.5229 

channel 10 

1.8114 

channel 11 

1.2151 

channel 12 

0.4677 

channel 13 

-1.2151 

channel 14 

0 

channel 15 

0.5229 


Return 

Close 


O O O Plane wave values 


Values for (azimuth, elevation) = (A,E) 
= (theta.phi) - (135,-45) : 


(_ 

dB ) 


N30 

channel 0 

0 

channel 1 

-1.24 

channel 2 

1.76 inverted 

channel 3 

-1.24 inverted 

channel 4 

-0.28 inverted 

channel 5 

2.73 inverted 

channel 6 

-5.05 

channel 7 

2.73 

channel 8 

silence 

channel 9 

-5.63 

channel 10 

5.16 

channel 11 

1.69 

channel 12 

-6.6 

channel 13 

1.69 inverted 

channel 14 

silence 

channel 15 

-5.63 


Return 

Close 
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* n ° p|ane wave values _ File manipulation 

Values for (azimuth, elevation) = (A,E) 

- (theta.phi) - (135,-45) Challenges 


voltage multiplier ^ 

( 

FuMa 

D 

channel 

0 

0.7071 

channel 

1 

0.5 

channel 

2 

-0.7071 

channel 

3 

-0.5 

channel 

4 

-0.5 

channel 

5 

-0.7071 

channel 

6 

0.25 

channel 

7 

0.7071 

channel 

8 

0 

channel 

9 

0.25 

channel 

10 

0.9186 

channel 11 

0.5446 

channel 12 

0.1768 

channel 13 

-0.5446 

channel 14 

0 

channel 15 

0.25 

( 

Return ^ 

( 

Close 
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A O O Plane wave values 

Values for (azimuth, elevation) = (A,E) 
= (theta,phi) = (67,-24): 


( voltage multiplier ) 


( 

FuMa 

J 

channel 

0 

0.7071 

channel 

1 

0.8409 

channel 

2 

-0.4067 

channel 

3 

0.357 

channel 

4 

0.6003 

channel 

5 

-0.684 

channel 

6 

-0.2518 

channel 

7 

-0.2903 

channel 

8 

-0.5797 

channel 

9 

-0.2732 

channel 

10 

-0.6343 

channel 

11 

-0.1055 

channel 

12 

0.4419 

channel 

13 

-0.0447 

channel 

14 

0.6126 

channel 

15 

-0.7117 

channel 

16 

undefined 

channel 

17 

undefined 

channel 

18 

undefined 

channel 

19 

undefined 

channel 

20 

undefined 

channel 

21 

undefined 

channel 

22 

undefined 

channel 

23 

undefined 

channel 

24 

undefined 
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About File Conversion 


( General V .amb to .caf I Merge If Split If Slim 1 
NOTES ON CONVERSION: 

The possibilities for file conversions are almost endless. 

As a starting point, a position has been taken that conversion from 
legacy formats are more important than conversion to legacy 
formats. 

This position is both practical (in the sense of the direction that 
file usage should be taking) and also based on the labour needed 
to construct such utilities. As legacy formats lack meta-data, then 
conversion requires software to determine (at best (or at worst, 
guess)) the format of the file to be converted. This, and the 
parallel ’sanity checking' restrain development. 

Suggestions for other conversions remain, though, welcome. 


File conversion 


File manipulation 


Challenges 


Paper 


A DTD for ambisonic... 


Home Page 


Title Page 


« ►► 


i ► 


Page 46 of 87 


Go Back 


Print 


Close 


Quit 










































Abstract 


Ambisonics 


Ambisuite 


Information utilities 


File conversion 


Ambisuite—GUI 


' File manipulation 


File conversion 


Information utilities 


ftOO 


About AMBISUITE 


About | Version^ Help ( Thanks 1 


ACKNOWLEDGEMENTS: 

* 

A special thanks to Rob and the rest of the SoX development team. 

Not just for SoX, but also for their patient listening to the various 
feature requests which were quite exotic compared with normal audio 
use, and their implementation -without which this work would not have 
been possible. 


Philip Cotterell and Fons Adriaensen kindly checked (and 
corrected) the early spherical harmonic equations. The former 
provided those for upto sixteenth order, and direction cosine 
versions upto sixth. 



Richard Dobson and Richard Furse for some interesting discussions. 
The former for putting the author right about WAVEX files, 
but most of all for persuading him that a GUI was 'do-able'. 

Franz Zotter for rotation matrix information for 90 degree 
pitches, used in various rotation calculations, and for his 
general and sustained encouragement. 

Chris Travis for information on (H,V,P) notation. 


File manipulation 


Challenges 


Paper 


A DTD for am bison ic... 


Home Page 


Title Page 


44 ►► 


◄ ► 


Page 47 of 87 


Go Back 


Print 


Close 


Quit 




















































Abstract 


Ambisonics 


Ambisuite 


Information utilities 


A special thanks to Rob and the rest of the SoX development team. 

Not just for SoX, but also for their patient listening to the various 
feature requests which were quite exotic compared with normal audio 
use, and their implementation -without which this work would not have 
been possible. 

Philip Cotterell and Fons Adriaensen kindly checked (and 
corrected) the early spherical harmonic equations. The former 
provided those for upto sixteenth order, and direction cosine 
versions upto sixth. 

Richard Dobson and Richard Furse for some interesting discussions. 

The former for putting the author right about WAVEX files, 
but most of all for persuading him that a GUI was 'do-able'. 

Franz Zotter for rotation matrix information for 90 degree 
pitches, used in various rotation calculations, and for his 
general and sustained encouragement. 

Chris Travis for information on (H,V,P) notation. 


File conversion 


File manipulation 


Challenges 


Paper 


A DTD for ambisonic... 


Home Page 


Title Page 


« ►► 


< ► 


Page 48 of 87 


Go Back 


Print 


Close 


Quit 






































6. File manipulation 


%o O File Manipulation 
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WOO About File Manipulation 

( General 

YAW / YAWING: 

A 'yaw' is an anticlockwise rotation of the soundfield about the 
z-axis. That is a 90 degree yaw moves Front to Left, Left to Back, 
etc. 

A 'yaw' can be applied to a file of any order. 

■Yawing' offers a progressive yaw. For example the soundfield can 
start in its original position and over the duration of the file 
it can move so what was front has become back. For the moment: 
first-order only. 


I Yaw/ing f Pitch/ing ¥ Roll/ing ¥ Rotate/ing 11 Shake ¥ Zoom/ing ¥ Place I 
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Manipulation - Yaw 



Use the keyboard 'up' and 'down' arrows to select alpha. 
Then 'return' to update the image. 

You may also type into the box: 0 <= alpha < 360. 
(Alpha is the new position of'Front' in degrees.) 



Next step (choose file) 
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7. Challenges 


Platform independence: 

• Minimal system calls 
Only two: 

- SoX 

- SoXI 
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Moving from command line to GUI and command line. 


Ambisonics 

Ambisuite 


• still not complete 

• major problem has been handling promiscuous messages 
sent to the terminal 

• subsets of which are ‘warning’ and ‘error’ messages. 
Whilst an ‘error’ may require a graceful death in command 
line mode (not least for batch processing), it requires dif¬ 
ferent handling in a gui. 
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The future: 

• Add ‘hyperambisonic’ utilities, if only for personal use. 

• SoX and Jack ... 

• Real-time modification of variables in SoX ? 

E.g. play -v 0.7 file.caf 
to play -v $vol file.caf 

with $ voi provided, say, by osc ??? 

• A GUI interface for rotations. 

• Is the ‘accepting in input; restrictive in output’ approach, 
the best way forward ... ? 
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8. Paper 


The text of the submitted paper is appended here. 

The paper was finalised several weeks before the slides and 
whilst the gui was still being developed. It does though give 
a more rigorous approach to the points discussed above, as 
well as providing references, etc. 
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8.1. Introduction 


Ambisonic 1 files are multi-channel audio files. They may, though, contain any number of 
channels (from a trivial one or two, but more realistically from three channels to an infinite 
number). 

The user of such files is confronted with two main problems: 


• Converting from one file format to another 

• Transforming [1] a signal set-for example rotating the soundfield 

The utility described uses a Perl [2] script as a wrapper to access the functionality of 
SoX [3] to allow such conversions and manipulations. 


8.1.1. Ambisonic file formats 


Classic formats 

The commonest format for ambisonics files, at the time of writing, is a form of wavex 
(Wave Format Extensible), which has a specific guid 2 (the equivalent of a uuid) and the 
suffix . amb. 

The format suffers from two main limitations: 

1 See Appendix (p. 79) for a brief description in relation to the terms used here. 

2 Acronyms are generally defined on fist occurrence in the body of the text. Common ones, which are not, are 
listed/defined in section 8.6. 
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- The limit on .wav file size * * 3 

- The non-explicit identification of channels 

For first order ambisonics the first is generally acceptable (a four channel ambisonic file 
has half the play time of a stereo file at the same sampling rate and bit-depth). The latter 
is circumvented by restricting usage to the first three orders (where channel count can be 
correlated to the format of the signal set 4 ). 

Its great attraction has been the ubiquity of applications that handle .wav. Despite that, 
applications that recognise . amb files are few, if any, and users have complained of having 
to rename the file (changing the suffix to .wav to use files). 

The need for a format to include higher order material 

There is an obvious need for a format that does not suffer (practical) file size limits and in 
which channels can be explicitly identified. 

From Ambisuite 0.6.0, a . caf format [5] is offered with its own specific uuid: 

“5dc3f270c2d24293858e64da38090bea” 

which also has a metadata chunk. This is more as ‘proof of concept’ than as a statement 
that this should be the new format. Comments from users are invited. 

The same uuid can be used in .wav files (implying an obligatory metadata chunk) al¬ 
lowing the same functionality for non-large files. This allows the lossless compression of 
WavPack [6] to be exploited. 

'4GB (though 2GB in some implementations), that is about 2 hours of 48KHz/24-bit 4 channel audio. Variants allow 

for a 64-bit file size description (as against 32) that remove this problem for practical purposes (‘W64’ and ‘RF64’) as does 

using metadata to chain files. 

4 See [4], If more complex mixed-order signal sets come into use (e.g. (H, V, P) sets, see page 80) then the situation is 
more complicated, and these could not all be implicitly determined. 
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The need for meta-data 

The trial . caf format (and related .wav files) use a chunk in xml to store metadata 
describing the file content. The dtd at: 

ambisonics.ch/dtds/ambisonic-0.03.dtd 
has been refined after discussion on the Ambisonics Association mailing list. 

The dtd countenances files in publication/exchange format (‘B-format’) as well as well as 
unprocessed microphone signals, the uhj broadcast formats, and ambisonics decoded 
to loudspeaker feeds (so called ‘A-’, ‘C-’ and ‘D-format’s). For B-format, of primary rele¬ 
vance to Ambisuite, it allows metadata to be stored on whether the signal set represents 
a two-, three-, mixed-, etc. dimensional soundfield and the assignment of the chan¬ 
nels of the file to ambisonic channels. It is intended that its style will be able to include 
developments in ambisonics without breaking backwards compatibility. 

It has been commented [7] that osc [8] may prove to be a better alternative than xml. 
Though generally associated with dynamic control of audio, osc has been used for static 
configuration files [9]. (There has also been talk -no more- of dynamically controlling SoX 
using OSC, which would be very interesting for ambisonic usage: for example to alter the 
aspect of (to rotate) a soundfield whilst it is playing.) 


8.1.2. Ambisonic manipulations 


The basic manipulations (other than adjusting amplitude/volume) are rotation and mirror¬ 
ing. A yaw (an anti-clockwise rotation about the z-axis) is easily achieved for a signal 
set of any order, likewise mirroring (shake). The other rotations (pitch, roll) have com¬ 
plicated transformation matrices and thus far are only implemented upto second order. 
Extension to higher orders will be accomplished along with generalised rotations (that is 
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not restricted to the planes of the axes). This though is a project for the future, indeed 
it has only just become practicable with Franz Zotter’s publication [10] of matrices upto 
twenty-first order, earlier this year. These are currently used in shake to allow simple 90° 
step rotations. 

Dominance ([11] p.5: a form of zooming) is only possible (for theoretical reasons) for first 
order files ([12] pp. 7-8). 

A mono sound can also be place d at a specific polar coordinate. The ability to do this is 
limited by the available spherical harmonic equations, that is upto sixteenth-order. 

A series of dynamic manipulations are being developed, e.g. such that yawing gradually 
rotates a signal set from one position to another. 

The other manipulations are of niche interest and documented in the software (e.g. ambman 
-help=a2b). 
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manipulation 

order 

a2b 

1* 

b2a 

1* 

mix 

OO 

normalise 

OO 

pitch 

2 

pitching 

0 

place 

16 

roll 

2 

rolling 

0 

shake 

21 

wxy2amb 

1* 

yaw 

OO 

yawing 

4 


Table 1: Manipulations offered by Ambman. The limits marked ‘*’ are the maximum allowable 
by ambisonics, rather than software limits. (‘0’ is not yet implemented.) 


8.2. Implementation 

8.2.1. Minimal system calls 


As the aim was for universality, then system calls have had to be curtailed, and the func¬ 
tionality of shell commands not used. Basic file and directory operations are carried out 
using Perl’s ‘filehandles, files and directories’ functions. The only call to Perl’s system 
function is to SoX and all such calls occur through one subroutine to ensure systematic 
error reporting should SoX fail (due to lack of discspace, a corrupt input file, or whatever). 
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8.2.2. Extensibility 


The aim has been to create ’any-order’ utilities. This meant abandoning classical channel 
sequence and channel weightings (the FuMa or Furse-Malham format [13]). That format 
is only applicable to the first three orders (upto sixteen channels), and its unsystematic 
approach makes software writing both difficult and prone to errors. Instead signals are in 
a normalised format (N3D ([14] pp. 155-157, esp. table 3.2 on p. 156)) and handled in the 
sequence of their ambisonic channel number (acn) [1 5]. 

Keeping it modular 

The aim has been that all data in the code (e.g. ‘look up tables’, equations) occur once 
only and then used if necessary by multiple subroutines. This eases both error detection 
and correction. All basic code is in a series of subroutines, whilst this makes the code 
verbose, it does facilitate later editing. 


8.2.3. Adding a GUI 


At the time of writing a GUI is being developed using the Tk toolkit [16] (version 8.5) 
accessed with the Perl Tkx package [17], Conceptually this is quite different from batch 
processing and has resulted in much code having to be rewritten. (The greatest work has 
been in having to change the promiscuous warning and error messages that were output 
to terminal to systematic ones that could be rendered on either terminal or gui.) 

It is an exciting challenge, and one that is probably essential if Ambisuite is to reach 
musicians, composers and others who may be averse to command line syntax. 
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8.3. Usage 

Whilst not the prime purpose of this paper, it would be remiss not to give a brief guide to 
using the utilities. 
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The compressed bundle can simply be opened in a directory and used there. To get the 
maximum benefit they should be installed (with root privileges) and then can be used 
anywhere. All the *.pl files (except libambisuite.pl) should be moved to a directory on 
the users’ search paths (/bin/ works fine on most systems). Renaming them by dropping 
the suffix (e.g. cp ambman.pl /bin/ambman) makes for easier use, and the GUI script 
can be renamed (i.e. cp ambisuite-gui.pi /bin/ambisuite). Permissions should 
already allow for execution but can easily be changed if necessary (e.g. chmod 755 
/bin/ ambman). 

The library of sub-routines (libambisuite.pl) needs to be in Perl’s search path (and should 
not be renamed). Trying to execute a mythical Perl program will cause Perl to list its search 
path (e.g. peri -e 'require " zyxw.pi ";'), and one of the listed directories can 
then be used as a location for ambisuite.pl. (E.g. /usr/iib/peri5/vendor_peri/.) 

The utilities can then be called in a terminal. Calling without options will give basic usage 
information, or they can be called with the option -help. (Sample terminal outputs for 
informational utilities are in figures 2, 3, 4 and 5.) As yet there is no icon for opening the 
GUI, but typing ambisuite and then return in a terminal will bring up the introductory 
window. 
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8.4. The Future 


There is still much work to be done, even in getting the present features running smoothly. 
User feedback is welcomed to assist with that process. 

Whilst a ‘modern’ file format has been proposed in the present release of Ambisuite, this 
is there very much as an example of how things may be. 5 If the ambisonic community 
can come together behind a file format, that will need incorporating. Most of the coding is 
though already there and adding a new format should now be relatively easy. 

The question of mixed-order files (see page 80) is somewhat unstable at present. Am¬ 
bisuite supports classical mixed order files, described by order (highest degree) and high¬ 
est periphonic degree. The dtd has scope for a third integer if/when more complex sets 
of mixed channels are standardised. 

The author [12] has a personal interest in hyperambisonics (the manipulation of four- 
five-dimensional, etc. soundfields) and the experimental code for this should be added, 
once tidied. 


5 Man is the only animal that can both laugh and cry: for he can see both how things are and how they might have been. 
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8.6. Acronyms 

Acronyms are generally defined in the text. The commoner ones, which are not, are 
defined here. 

DTD Document Type Definition [18] 

GUI graphical user interface (a window/icon/mouse/pointer access to a program, rather 
than a terminal) 

GUID globally unique identifier (Microsoft’s implementation of uuids). 

N3D [14], pp. 155-157, esp. table 3.2 on p. 156 
PDF Adobe’s Portable Document Format 

UUID universally unique identifier (man uuidgen for basic information. 

XML Extensible Markup Language [18] 
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( 45 , - 45 ) 


ambcalcis a Perl program that calculates various factors 
relating to Ambisonic files. 

checking and re-cliecking line-by-line. Do use. Do enjoy. Bui 
do check for any usage that is critical! — Bug reports are more 

Your request was for: 

angle = a = 8 = 45 degrees 


elevation = e (= b) = tj> = -45 degrees 



Figure 1: PDF output (in FuMa) of Ambcalc 
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]$ ambcalc 

AMBCALC 0.5.3, 2007/09/18 - Copyright (c) 2007 by Michael 

This is an early release for comments, the equations need 
checking and re-checking. Do use. Do enjoy. But do check 

for any usage that is critical! - Bug reports are more 

than welcome: ambsuite@mchapman.com 

type q to quit, h for help 

angle (a): 45 
elevation (e): -45 
channel i value ( dB ) 


W -3.01 

X -6.02 

Y -6.02 

Z - -3.01 


A in the "i" column indicates the track is inverted 
relative to the W track (that is the amplitude is 
negative). 
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Figure 2: Terminal output (in FuMa) of Ambcalc. 















]$ ambchan hv=4,2 

AMBCHAN 0.5.3, 2008/09/18 - Copyright (c) 2008 by Mich 

Channels for (H,V) = (4,2): 

(Malham notation = ffhh.) 

0,1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 16, 24 
Total channels used = 13. 

1 m ACN 

0 0 0 
1-11 
10 2 
113 
2-2 4 

2- 15 

2 0 6 

2 17 
2 2 8 

3- 3 9 

3 3 15 

4 -4 16 

4 4 24 

Figure 3: Terminal output of Ambchan, giving channels in a (h, v ) = (4, 2) file. 


]$ ambchan R 

AMBCHAN 0.5.3, 2008/09/18 - Copyright (c) 2008 by 
AMBIS0NIC CHANNEL: 

6 -ambisonic channel number (ACN) 

2,0 -(l,m) — (order,range) 

R -channel letter (if appropriate). 

The formula for the spherical harmonic associated 
with this second degree component can be found at: 
http://ambisonics.ch/standards/channels/ACN6 
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Figure 4: Terminal output of Ambchan, giving synonyms for channel R. 













]$ ambinfo MC_26-positions.amb 

AMBINFO 0.5.4, 2008/10/31 - Copyright (c) 2007-8 by Michael 

SUMMARY; (run with -v for more details) 

Channels: 4 

Implicitly a first order file 
channels (I am guessing) are WXYZ 

48 KHz / 24 bits / PCM / AMBIS0NIC 

estimated duration 130 seconds: 


Figure 5: Terminal output of Ambinfo. 
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Appendices 


Download and licence 

Ambisuite consists of a GUI called by the command ambisuite, and command line utili¬ 
ties: 

ambman —the basic manipulation (conversion and transformation) program 
ambcaic — prints out channel values for a given azimuth and elevation 
ambchan — converts channel names/notations, and likewise for groups of channels 
ambinfo — reads a WAVEX header and outputs to terminal 
amb2caf — converts a classic . amb file to a . caf file with metadata 

wav2amb — ‘corrects’ the headers on Wave Format Extensible files creating a . amb 
file 


It has a recent Sourceforge page (http://ambisuite.sourceforge.net/) though 
most of the material Still resides at http://mchapman.com/amb/soft/index. The 
Sourceforge site 6 also contains the ‘forum’ for help, bug reports and feature requests. 

It requires Perl (almost any version) for all operations, the audio manipulations require SoX 
(latest version) and the GUI requires the Tk toolkit and Perl Tkx (see above for references 
giving urls). 

Ambcaic will present a nice pdf output (see figure 1) as well as the terminal output. (A 
I/TeX file is optionally produced and can be processed with pdf latex or similar.). 


6 https://sourceforge.net/forum/forum.php?forum_ id=898927. 
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Abstract 



utility 

Perl 

SoX 

ambman 

yes 

yes 

ambcalc 

yes 

no 

ambchan 

yes 

no 

ambinfo 

yes 

no 

amb2caf 

yes 

yes 

wav2amb 

yes 

yes 


Table 2: Dependencies 


Ambisonics 
Ambisuite 
Information utilities 
File conversion 
File manipulation 
Challenges 
Paper 

A DTD for ambisonic... 


It is released under the GNU General Public License, version 3. 


Note 


This paper was written as 
show some slight variation. 


some of the code was being finalised. The released version 0.6.0 may 
(Screenshots, etc. are from version 0.5.*.) 
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Ambisonics 


Unfortunately it is difficult to give an appropriate reference explaining basic ambisonics. 
Malham [13] though excellent covers material most likely well known to most ambisonic 
users. For the newcomer, reading this paper, the differences in channel notation, se¬ 
quence and weightings is likely to be a hurdle. 

The basics used here are explained below. 
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channels 


An ambisonics signal set represents sound from all directions. That is from the full 360° for 
two dimensions (paritophony) or a full sphere ( periphoriy ). Hybrids of these are possible 
(see Mixed Order Sets below.) The accuracy of the representation is increased by adding 
more channels, these are added in discrete groups or degrees. 

The fact that a full soundfield is represented, means that transformations [1] -such as 
rotating the soundfield- are possible. 

An ambisonic signal set is described as being of a certain order. 7 

Zero-order is possible, it comprises one channel and is effectively omni-directional mono. 

For practical ambisonic files it is necessary to add first- (second-, etc) degree signals. 
Thus a third-order file contains zero-, first-, second- and third-degree signals. 

7 Here order refers to the entire signal set/file, whilst degree refers to each spherical harmonic degree. Previously order 
has been used by some authors for both terms. 
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For pantophony each additional degree consists of two channels. So the channel count is 
21 + 1, where l is the order. 


For periphony the number of channels in each degree is different (3, 5,7,...) and the 
channel count is (l + l) 2 . 

The channels within a degree are referred to by their order (not to be confused with am- 
bisonic order) m, with —l>m>l. Pantophonic sets only contain channels with m = ±1. 

It is convenient to give a unique integer to each channel (not least for ordering them in a 
file), the ambisonic channel number (acn), given by 1(1 + 1) + to. 

Acns 0 to 15 correspond, respectively, to the FuMa letter codes W YZX VTRSU QOMKLNP. 
(There are no letter codes for higher channels. FuMa also applies a (non-normalised) 
’weighting’ (an amplitude factor) to each channel [1 3]). 

A generalised notation for channels uses l and to, with each channel designated BY 1 . If 
acns are used the simpler B n where n is the acn can be used. 


mixed order sets 


Traditionally mixed order signal sets have the lower degree(s) in periphony and the higher 
one(s) in pantophony. This gives accurate horizontal representation and a more limited 
representation of ‘height’ information. This corresponds with the soundstage for per¬ 
formed music. 


Classically these were periphonic (three-dimensional in lower degrees) with pantophony 
in higher degrees. Ambisuite (and the dtd it uses) currently recognises this system. 
However other mixes are possible, for example second-order with all components except 
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channel 6 (R). This eight channel signal set is all that is needed, for example, for playback 
on a cuboidal rig 8 and also has the convenience of being losslessly compressible in a 
flac file. These more complex mixed order sets need three integers to describe them. 
The current favoured notation is ( H,V,P ), though this remains to be standardised and 
published. 


For a more detailed explanation of these signal set terms, and their usage see Cotterell & 
Chapman [1], 


Abstract 
Ambisonics 
Ambisuite 
Information utilities 
File conversion 
File manipulation 
Challenges 
Paper 

A DTD for ambisonic... 


8 Channel 6 is a “discarded ambiguous harmonic”, see Richard Furse’s First and Second Order Ambisonic Decoding 
Equations (at www. muse . demon. co. uk/ref/speakers . html) (and unlike channel 8 (U) has no potential use if it 
is desired to yaw the soundfield.) 
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9. A DTD for ambisonic metadata in XML 

<!ATTLIST ambisonic xmlns:xlink CDATA #FIXED 
"http://www.w3.org/1999/xlink3"> 

<!— This is "ambisonic-0.04.dtd" 
early DRAFT of 2009-02-15 

Copyright (c) 2009 The Ambisonics Association. 

—> 

<!— revision history 
0.01 DRAFT of 2008-09-25. 

0.02 now includes more for a, c and d_format 
0.03 includes (H,V,P) and allowed for alternative 
rigs (e.g. made 'square' 'squarel') 

0.04 includes UHJ (true -and- UHJ:L+R). 

—> 

<!— Each XML file must have a set of 'form' metadata, 
and may contain a set of 'function' metadata. 

The former is technically what the file is. 

The function metadata is about the file (e.g. 
recording engineer's name!) 

(Better names welcomed.) —> 
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<[ELEMENT ambisonic (form, function?)> 












<!ELEMENT form (a_format | b_format | c_format | d_format )> 

<!ELEMENT a_format (mics, name?, calibration*)> 

<!ELEMENT mics (position!)> 

<!ATTLIST mics number NMTOKEN #REQUIRED> <!— 
number of capsules —> 

<!ELEMENT position (NMTOKEN) > 

<!ATTLIST position channel NMTOKEN #IMPLIED> 

<!— implicit which one refers to which channel, 
but numbering them off makes it more human 
readable/friendly —> 

<!ELEMENT name (#PCDATA)> <!— human readable microphone name—> 
<!ELEMENT calibration (#PCDATA)> 

<!— Include the mic's calibration file verbatim. 

If verbatim include in "<!CDATA[" flags "]]>" 

—> 

<!ATTLIST calibration type NMTOKEN #IMPLIED> 

<!— TetraMic offers two files one for Windows, 

one for TetraProc so we give a chance 

to have more than one, and to 

have a type="TetraProc" attribute. —> 


<!ELEMENT b_format (dimensions, extra*)> 

<!— We require one piece of data: 'dimensions'. 
This must be an integer. ( 

(e.g. "2" for pantophonic 
"3" for periphonic) 

We _may_ also have extra channels, that 
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should be ignored. —> 

<!ELEMENT dimensions (dimension!)> 

<!ATTLIST dimensions number NMTOKEN #REQUIRED> 

<!ELEMENT dimension EMPTY> 

<!— We describe what channels are present in (H,V,P) 

notation 

(1,1,1) is periphonic of order 1 

(1,0,p) is traditional mixed order of order 1, 

and full periphony upto order p 

(p<l, obviously). 

(If p=0, that is simple pantophony.) 

Other values are possible, but the above 
should cover existing files. —> 

<!ATTLIST dimension 
H NMTOKEN #REQUIRED 

V NMTOKEN #REQUIRED 

P NMTOKEN #REQUIRED 

> 

<!ELEMENT extra (#PCDATA) > 

<!ATTLIST extra ch_number NMTOKEN #REQUIRED> 

<!— the 'extra is rather gratuitous but does enable 
tracks to de added (click tracks, labels tracks, 
even a voice memo track. The intention (if decoders 
even implement this) is that decoders just ignore 
these tracks. —> 

<!ELEMENT c_format EMPTY> 

<!— "C-format" is synonymous with UHJ —but see note below! —> 
<!ATTLIST c_format type ( BHJ | SHJ | THJ | PHJ ) #REQUIRED> 
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<!— that is 2, 2.5, 3 and 4-channel UHJ respectively, 
channels SD (T (Q)) . 

What is commonly called "UHJ" is a decoding to 
L(eft) and R(ight) speaker feeds of one of the 
above (T and Q are unused, if present). 

UHJ:L+R is a D-format, see below ... —> 

<!ELEMENT d_format ( short | code I coord ) > 

<!ELEMENT short EMPTY> 

<!ATTLIST short rig ( UHJ | monol | stereol | squarel | pentagonl| 
hexagonl | hexagon2 | octagonl | octagon2 | 
surround5 | cubel I dodecahedronl 
dodecahedron2 ) #REQUIRED> 

<!— These are from Furse, and obviously can 
be added to without breaking backwards 
compatibility. —> 

<!— UHJ is the Left+Right decode of true UHJ. 

It is for a stereo rig, but probably 
worth listing as something 
in its own right! 

For 'true' (un-decoded) UHJ see 
C-format, above. —> 

<!ELEMENT code (channel!) > 

<!ELEMENT channel (NMTOKEN) > 

<!— number <= three digits from CAF specification, 
pp 35-36 —> 

<!ATTLIST channel number NMTOKEN #IMPLIED> 

<!— make human readable by numbering off the 
channels -optional —> 
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<!ELEMENT coord (channel+) > 

< ! — 'channel' 

comma separated list of polar coordinates 
loudspeakers seem to have F=0,0; R=90,0; U=0,90 
contrary to ambisonics ...! 

Probably should allow single values, with 
implied phi=0 (but 

only if applied to all values. —> 

<!— 'channel number' (as above 

make human readable by numbering off the 

channels -optional —> 
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<!— That is the basics done !—> 

<!ELEMENT function (tag*, attach*)> 

<!— We allow non-technical metadata. 

Decoders may ignore all this. —> 

<!ELEMENT tag (#PCDATA) > 

<!— The intention is to allow elements such as 
<tag tag_id="composer">Johann 
Sebastian Bach</tag> 

There is a total free choice of tag_id's. The same 
tag_id may be used more than once. 

Conventions for 'composer', 'title', etc. should 
though be followed. 
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— > 


<!ATTLIST tag tag_id CDATA #REQUIRED> 












<!ELEMENT attach (#PCDATA) > 

<!— We also allow attached files. E.g.: 

<attach source="Bach.jpg" tag_ref="composer" 
alt="Photograph(sic) 

of JSB">JS Bach photographed at his first 
concert</attach> 

The tag_ref and alt are optional. 
tag_ref ties the attachment to a tag_id (if desired) 
alt follows HTML guidelines 
—> 

<!ATTLIST attach source CDATA #REQUIRED 
tag_ref CDATA #IMPLIED 
alt CDATA #IMPLIED 


<!— END OF ambisonic-*.dtd —> 
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